Scripting
Documentation
Changelog
Privacy
Documentation
Changelog
Privacy

Symbol Style

These modifiers allow you to customize how SF Symbols are displayed and animated inside views, particularly with the Image component.

symbolRenderingMode

Sets the rendering mode for symbol images within the view.

Type

1symbolRenderingMode?: SymbolRenderingMode

Options (SymbolRenderingMode)

  • "monochrome" – A single-color version using the foreground style
  • "hierarchical" – Multiple layers with different opacities for depth (good for semantic coloring)
  • "multicolor" – Uses the symbol's built-in colors
  • "palette" – Allows layered tinting (like using multiple foregroundStyle layers)

Example

1<Image
2  systemName="star.fill"
3  symbolRenderingMode="palette"
4  foregroundStyle={{
5    primary: "red",
6    secondary: "orange",
7    tertiary: "yellow"
8  }}
9/>

Explanation:

  • symbolRenderingMode="palette" tells the system to render the symbol in multiple layered styles.
  • foregroundStyle now uses an object with primary, secondary, and optionally tertiary layers to color those symbol layers individually.

This matches SwiftUI's behavior with .symbolRenderingMode(.palette) and .foregroundStyle(primary, secondary, tertiary).

symbolVariant

Displays the symbol with a particular visual variant.

Type

1symbolVariant?: SymbolVariants

Options (SymbolVariants)

  • "none" – Default symbol with no variant
  • "circle" – Encapsulated in a circle
  • "square" – Encapsulated in a square
  • "rectangle" – Encapsulated in a rectangle
  • "fill" – Filled symbol
  • "slash" – Adds a slash over the symbol (often used to indicate "off" states)

Example

1<Image
2  systemName="wifi"
3  symbolVariant="slash"
4/>

symbolEffect

Applies a symbol animation effect to the view. This can include transitions (appear/disappear), scale, bounce, rotation, breathing, pulsing, and wiggle effects. You can also bind the effect to a value so it animates when the value changes.

Type

1symbolEffect?: SymbolEffect

There are two forms of usage:

1. Simple effects (transition, scale, etc.)

You can directly assign a symbol effect name:

Examples

1<Image
2  systemName="heart"
3  symbolEffect="appear"
4/>
5
6<Image
7  systemName="checkmark"
8  symbolEffect="scaleByLayer"
9/>

2. Value-bound discrete effects

These effects animate when the associated value changes.

Type

1symbolEffect?: {
2  effect: DiscreteSymbolEffect
3  value: string | number | boolean
4}

Example

1<Image
2  systemName="star.fill"
3  symbolEffect={{
4    effect: "bounce",
5    value: isFavorited
6  }}
7/>

In this example, each time isFavorited changes, the bounce animation is triggered.

Available Discrete Effects (DiscreteSymbolEffect)

These effects can be bound to values:

Category Effects
Bounce bounce, bounceByLayer, bounceDown, bounceUp, bounceWholeSymbol
Breathe breathe, breatheByLayer, breathePlain, breathePulse, breatheWholeSymbol
Pulse pulse, pulseByLayer, pulseWholeSymbol
Rotate rotate, rotateByLayer, rotateClockwise, rotateCounterClockwise, rotateWholeSymbol
VariableColor variableColor, variableColorCumulative, variableColorDimInactiveLayers, variableColorHideInactiveLayers, variableColorIterative
Wiggle wiggle, wiggleByLayer, wiggleWholeSymbol, wiggleLeft, wiggleRight, wiggleUp, wiggleDown, wiggleForward, wiggleBackward, wiggleClockwise, wiggleCounterClockwise

Full Example

1<Image
2  systemName="bell.fill"
3  symbolRenderingMode="hierarchical"
4  symbolVariant="circle"
5  symbolEffect={{
6    effect: "breathePulse",
7    value: isNotified
8  }}
9  foregroundStyle="indigo"
10/>

This image uses:

  • a hierarchical rendering mode
  • a circular variant around the symbol
  • a pulsing animation bound to isNotified state

Summary

Modifier Description
symbolRenderingMode Sets how SF Symbols are rendered (monochrome, multicolor, etc.)
symbolVariant Applies a visual variant like fill, circle, or slash
symbolEffect Adds visual animation effects; can be static or bound to a state change
Outline